home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / What's New? / Development Kits / Mac OS / USB DDK 1.4.6f4 / Mac OS USB DDK Readme < prev   
Encoding:
Text File  |  2000-09-26  |  14.9 KB  |  343 lines  |  [TEXT/ttxt]
  1.  ***
  2.  ***   Universal Serial Bus(tm) (USB) for the Mac OS
  3.  ***   Mac OS USB 1.4.6f4 Driver Development Kit (DDK) Release Notes
  4.  ***   Copyright 1998-2000 Apple Computer, Inc.
  5.  ***
  6.  
  7.  *** IMPORTANT *** IMPORTANT *** IMPORTANT *** IMPORTANT ***
  8.  
  9. The USB Support and USB Device Extension files may not be distributed 
  10. in any manner. These files are for developer use only, and are NOT
  11. TO BE INCLUDED with the components installed with your product.
  12.  
  13.  
  14.  Table of Contents:
  15. -------------------------------------------------------------
  16.  Changes in Mac OS USB -> 1.4.6
  17.  System Requirements for USB 1.4.6
  18.  USB Fundamentals
  19.  Keeping up to date on Mac OS USB
  20.  Getting started with Mac OS USB
  21.  Installing the Mac OS USB Software
  22.  Using the Mac OS USB DDK under MPW
  23.  Using the Mac OS USB DDK with Metrowerks CodeWarrior
  24.  Installing the Mac OS USB DDK for CodeWarrior for the First Time 
  25.  Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  26.  Using the CodeWarrior Project Files
  27.  Description of Installed Files
  28.  Known Problems and Issues
  29.  Contact / Marketing Information
  30. -------------------------------------------------------------
  31.  
  32.  
  33. Changes in Mac OS USB -> 1.4.6f4
  34. ------------------------------
  35.  
  36. Refer to the document "Mac OS USB Change History" in the Documentation folder for a description of the changes between versions of USB. 
  37.  
  38. This DDK requires that you have Universal Interfaces and Libraries 3.3.1 installed in your development environment. You can obtain these files from the Apple Developer Connection Software Development Kits web page: 
  39.  
  40. <http://developer.apple.com/sdk/>
  41.  
  42. The two common symptoms that you have not yet installed these files will be:
  43. 1. There is a compile time error that the header file "MacErrors.h" could not be found
  44. 2. There is a link error that the file HIDLib could not be found.
  45.  
  46. Both files are included with Universal Interfaces and Libraries 3.3.1.
  47.  
  48.  
  49. System Requirements for USB 1.4.6f4
  50. ---------------------------------
  51.  
  52. Apple is formally qualifying USB 1.4.6f4 on the Macintosh systems with built-in USB and with an update to Mac OS 9.0.4 installed. You can also test with Mac OS 9.0 and 9.0.4. Mac OS USB 1.4.6f4 will work with Power Macintosh systems with OHCI-based USB PCI or USB Cardbus cards installed. To test with USB v1.4.6f4, first install Mac OS 9.0.4, then follow the instructions below. Important note: Mac OS USB 1.4.6 will only be available on systems with the update to Mac OS 9.0.4 installed.
  53.  
  54.  
  55. USB Fundamentals
  56. ----------------
  57.  
  58. Apple is no longer shipping Macintosh systems with ADB or serial ports. USB is now the primary interface for connecting low- and medium-speed peripheral devices. There are numerous advantages for adopting the USB standard on Macintosh discussed in the "Mac OS USB DDK API Reference Guide."
  59.  
  60. The DDK provides the tools, interfaces, system software, and module examples for you to start developing USB products for the Macintosh. 
  61.  
  62.  
  63. Keeping up to date on Mac OS USB
  64. --------------------------------
  65.  
  66. To stay abreast of changes in Mac OS USB, check out the Mac OS USB Developer web site for the latest information. As updates to Mac OS USB occur, development releases of the software will be made available from this web site. The URL for the web site is:
  67.  
  68. <http://developer.apple.com/dev/usb>
  69.  
  70. You can also subscribe to the Mac OS USB Developer mailing list where development questions regarding Mac OS USB are posed and answered. To submit a question to the mailing list you must first be a subscriber. To subscribe to the mailing list, send an email with the subject "subscribe usb" (omit the double quotes) to requests@isg.apple.com.
  71.  
  72. Use the following URL to accomplish this:
  73.  
  74. <mailto:requests@isg.apple.com?SUBJECT=subscribe usb>
  75.  
  76. USB Alerts to developers are always posted to the mailing list. These alerts are also posted to the Mac OS USB Developer Web site at the following location:
  77.  
  78. <http://developer.apple.com/dev/usb/devalerts.html>
  79.  
  80.  
  81. Getting started with Mac OS USB
  82. -------------------------------
  83.  
  84. To develop with Mac OS USB v1.4.6f4, you will need a Power Macintosh system with USB built in or with a USB PCI adapter installed. This release of Mac OS USB also supports USB Cardbus cards on PowerBook G3 Series systems with Mac OS 9.0.4 or later.
  85.  
  86. USB v1.4.6f4 will support PCI USB cards from several vendors. However, the enclosed software is for developmental purposes and is not directly supported by Apple, nor is it intended for end-users. End-user customers are encouraged to download the standalone USB Adapter Card Support Installer rather than use the extensions provided in this DDK. 
  87.  
  88. You may find that development on a Power Mac system with a USB PCI card and serial port is easier, as you can use the Power Mac Debugger with a second Power Macintosh system. A Power Macintosh system with ADB keyboard is useful for debugging with Macsbug, since there are cases when the system cannot process keystrokes from a USB keyboard.
  89.  
  90.  
  91. Installing the Mac OS USB Software
  92. ----------------------------------
  93.  
  94. Before using the enclosed software on a Macintosh system with built-in USB you must already have Mac OS USB 9.0.4 or later present. If the Mac OS ROM file includes this release of USB, do not install the system extension components from this DDK to the Extensions Folder.
  95.  
  96. To install the USB System Software components, 
  97.  
  98. 1. Remove all files with the following names from your Extensions Folder. 
  99.  
  100.  USB Support,
  101.  USB Device Extension,
  102.  USBCompositeDriver,
  103.  USBFamilyExpert,
  104.  USBHIDKeyboardModule,
  105.  USBHIDMouseModule,
  106.  USBHIDUniversalModule,
  107.  USBHubDriver0,
  108.  USBHubDriver1,
  109.  USBOpenHCIDriver,
  110.  USBPrintDriver,
  111.  USBCommClass,
  112.  SerialShimLib,
  113.  HID Library,
  114.  USB Software Locator,
  115.  USB Power Class,
  116.  USB Mass Storage Extension,
  117.  USB Mass Storage Support
  118.  EnetShimLib
  119.  
  120. 2. Drag copy the contents of the folder
  121.  
  122.   :Extensions-AppleBuilt: 
  123.  
  124. to the Extensions folder.
  125.  
  126. 3. Reboot your system after making this modification.
  127.  
  128.  
  129. Important Notes on Installation and Use of this DDK software
  130. ------------------------------------------------------------
  131.  
  132. This DDK will let you look at the sources to some working class drivers, build the examples, and develop and build your own code.
  133.  
  134. Please remember that these driver samples are copyright Apple Computer, Inc. You may use the supplied code to develop Class Drivers for your devices. As for publishing the source code, please
  135. check first with the Mac OS USB DDK License agreement included in this DDK.
  136.  
  137. The current driver samples may reflect the latest state of the art of USB driver writing for Mac OS. Note that the PrinterClassModule and the USBSampleStorageDriver samples are for example purpose only. These samples are derived from the shipping drivers: however, we are unable to provide the actual class driver code. The remaining examples are the real code for the Keyboard HID, Mouse HID, Universal HID, and Composite class drivers which ship as part of Mac OS.
  138.  
  139. While not extensively tested (by the development team), the sample sources have been tweaked slightly to ease the build process when using the Metrowerks Codewarrior IDE. The project files 
  140. are provided to help jumpstart your development process.
  141.  
  142. It is highly recommended that you use one Macintosh for coding purposes and a second (aka "Target") system for checkout/testing purposes.
  143.  
  144.  
  145. Using the Mac OS USB DDK under MPW
  146. ----------------------------------
  147.  
  148. For previous releases of the USB DDK, we provided a current UserStartup•USBDDK and makefiles for each of the sample class drivers. As there are very few developers who use the MPW environment for creating USB drivers we no longer provide an MPW UserStartup file or makefiles for the class driver samples.
  149.  
  150. If MPW is your primary development platform and you need a makefile for one of the example class drivers, submit a request to the Mac OS USB mailing list and a sample makefile, if available for the example, will be sent to you. See the section "Keeping up to date on Mac OS USB" above for information on how to subscribe to the Mac OS USB Developer mailing list.
  151.  
  152. If you do use MPW, you must update your libraries and Interfaces to Universal Interfaces and Libraries v3.3.1 or later.
  153.  
  154.  
  155. Using the Mac OS USB DDK with Metrowerks CodeWarrior
  156. ----------------------------------------------------
  157.  
  158. This DDK includes Metrowerks CodeWarrior project files for all of the USB code samples. All of the project files were created using CodeWarrior Pro 1 (IDE 2.0) or later. These project files can also be used with newer versions of CodeWarrior Pro.
  159.  
  160. The examples require version 3.3.1 of Universal Interfaces and Libraries and may not build using the interfaces and libraries supplied with older versions of CodeWarrior Pro. You can obtain these files from the Apple Developer Connection Software Development Kits web page: 
  161.  
  162.   <http://developer.apple.com/sdk/>
  163.  
  164. The supplied project files will place the built drivers and extensions into the "Extensions-MCWBuilt" folder of the DDK.
  165.  
  166.  
  167. Installing the Mac OS USB DDK for CodeWarrior for the First Time
  168. ----------------------------------------------------------------
  169.  
  170. 1. You can place the Mac_OS_USB_DDK anywhere on your development
  171.    system for the CodeWarrior environment. The access paths
  172.    for the project files are project and compiler relative.
  173.    If you move the examples folders out of the DDK, you must
  174.    fix the access paths so that the sources can be found.
  175.  
  176. 2. Ensure that the CodeWarrior IDE environment has at least the 
  177.    Universal Interfaces and Libraries 3.3.1 installed. The
  178.    download file from the DDK website includes instructions
  179.    for upgrading your Codewarrior environment. Note that if
  180.    you upgrade your interfaces, you will also need to 
  181.    upgrade your precompiled headers. The supplied CodeWarrior
  182.    project files do not use precompiled headers.
  183.  
  184. 3. Replace the USB.h and HID.h files in your CodeWarrior headers
  185.    with the versions included in this DDK.
  186.  
  187. 4. You will find that the project files will place the built drivers
  188.    and extensions into the folder:
  189.  
  190.    ":Extensions-MCWBuilt"
  191.  
  192.    If this folder does not exist, or the folder name is different,
  193.    the class driver samples will be created in the CodeWarrior folder.
  194.  
  195.  
  196. Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  197. --------------------------------------------------------------
  198.  
  199. 1. Ensure that you have the Universal Interfaces and Libraries 3.3.1
  200.    installed in your CodeWarrior environment. If an earlier release of
  201.    the Universal Interfaces and Libraries is used, you may receive
  202.    numerous compiler errors.
  203.  
  204. 2. Replace the USB.h and HID.h files in your CodeWarrior headers
  205.    with the versions included in this DDK. Do not
  206.    use the header files from an earlier USB DDK with the
  207.    supplied project files, as the examples may not build.
  208.  
  209.  
  210. Using the CodeWarrior Project Files
  211. -----------------------------------
  212.  
  213. For the following samples, the projects contain only a single target:
  214.  
  215.   CompositeClassDriver
  216.   DropPrint•USB
  217.   HIDReader
  218.   KeyboardModule
  219.   MouseModule
  220.   PowerClassQueryDevice
  221.   UniversalModule
  222.   USBKeypad
  223.   USBModem
  224.   USBMultModule
  225.   USBTabletModule
  226.  
  227. For the PrinterClassDriver example build the targets in the following order:
  228.  
  229.  1. PrinterClassDRVR - creates the 68K DRVR resource
  230.  2. PrintClassDriver - creates the USB PrintClassDriver module
  231.  
  232. For the PrintChooserSample example build the targets in the following order:
  233.  
  234.  1. ChooserPack.rsrc - creates the "PACK" resource
  235.  2. USB Chooser Driver - creates the Chooser extension for the 
  236.     USB printer
  237.   
  238. For the USBSampleStorageDriver example build the targets in the following order:
  239.  
  240.  1. USBStorageClassDriver - creates the USB StorageClassDriver module
  241.  
  242.     The other two targets will be built automatically:
  243.  
  244.  USBStorageClassShim - creates the shim module which loads the unit
  245.               table driver when the device is attached
  246.  USBStorageClassUTDriver - auto built into shim - native driver
  247.               compiled as a resource into the shim file.  
  248.       
  249.  
  250. Known Issues
  251. ------------
  252.  
  253. The following is a list of known issues with this release of the USB DDK.
  254.  
  255.  
  256.  
  257. Contact / Marketing Information
  258. -------------------------------
  259.  
  260. Mac OS USB DDK Upgrades and latest information:
  261.  
  262.  For the latest information on the Mac OS USB DDK, refer to the Mac OS USB web page. The latest 
  263.  shipping and pre-release versions of Mac OS USB will be accessible there:
  264.  
  265.   <http://developer.apple.com/hardware/usb/>
  266.  
  267.     Check the Software Development Kits web page for    other SDKs which you may need. The URL is:
  268.         
  269.         <http://developer.apple.com/sdk/>
  270.  
  271.  For Bug Reports:
  272.  
  273.   To ensure the appropriate data is collected, please use the Bug Reporter 
  274.   to send us your bug reports. The Bug Reporter can be found at: 
  275.  
  276.   <http://developer.apple.com/bugreporter>
  277.  
  278.   When reporting problems, please include your machine configuration. If you are 
  279.   testing with a USB PCI card please include the vendor of the card you are using.
  280.  
  281.  For Technical Questions:
  282.  
  283.         For generic Mac OS USB questions, submit them to the Mac OS USB 
  284.   Developer mailing list. Refer to the section above "Keeping up to date 
  285.   on Mac OS USB" for information on how to subscribe to this mailing list.
  286.   Often questions can be answered by someone on the mailing list.
  287.  
  288.         If your question is not answered on the mailing list, or if your question 
  289.   is proprietary, contact Worldwide Developer Technical Support with purchased development-level 
  290.   technical support incidents at
  291.  
  292.   <mailto:dts@apple.com>
  293.  
  294.   Technical support incidents are bundled in our Premier and Select 
  295.   Developer programs. For information about joining our programs, 
  296.   please visit our Apple Developer Connection web site at 
  297.  
  298.   <http://developer.apple.com/membership/descriptions.html>
  299.  
  300.   If you have never purchased a technical support incident and would like 
  301.   to find out how to do so, please visit the following site: 
  302.  
  303.   <http://developer.apple.com/programs/techsupport.html> 
  304.  
  305.     
  306.  Comments, Suggestions and Enhancement Requests
  307.  
  308.   Please send all comments and suggestions regarding the Mac OS USB DDK to
  309.     
  310.   <mailto:usb@apple.com>
  311.  
  312.   All email sent to this address will be read: however, we will not be able to
  313.   respond to all of your comments and suggestions.
  314.  
  315.         
  316.  Marketing Information:
  317.  
  318.   Registering Your Product - Apple provides the Macintosh Products Guide page 
  319.   as a reference source for all Macintosh Products. You can register your USB 
  320.   Product with the Macintosh Products Guide, by going to the Product 
  321.   Submission Form web page and and submitting the requested information. The
  322.   Macintosh Products Guide web page address is
  323.  
  324.   <http://guide.apple.com/>
  325.  
  326.   The Product Submission Form web page address is:
  327.  
  328.   <http://submit.macsoftware.apple.com/SubmissionChoice.html>
  329.  
  330.  
  331.   Licensing Apple Software / Logo - If you will need to license Apple software, 
  332.   refer to the Apple Software License web page a listing of licensable software 
  333.   and for the procedure to obtain the license. The Mac logo is also licensable 
  334.   from the Apple Software License web page. The Apple Software License web page
  335.   address is:
  336.  
  337.   <http://developer.apple.com/mkt/swl/>
  338.  
  339.   To display the USB logo, contact the USB IF at the following web page:
  340.  
  341.   <http://www.usb.org/developers/>
  342.  
  343.